// 版权所有2009 Go作者。版权所有。
// 此源代码的使用受BSD样式
// 许可证的约束，该许可证可以在许可证文件中找到。

// Cgo；见医生。浏览一下概览。

// TODO（rsc）：
// 发出正确的行号注释。
// 让gc理解注释。

package main

import (
	"crypto/md5"
	"flag"
	"fmt"
	"go/ast"
	"go/printer"
	"go/token"
	"internal/buildcfg"
	"io"
	"io/ioutil"
	"os"
	"path/filepath"
	"reflect"
	"runtime"
	"sort"
	"strings"

	"cmd/internal/edit"
	"cmd/internal/objabi"
)

// 一个包收集关于我们将要编写的包的信息。
type Package struct {
	PackageName string // 包名
	PackagePath string
	PtrSize     int64
	IntSize     int64
	GccOptions  []string
	GccIsClang  bool
	CgoFlags    map[string][]string // /#cgo标志（CFLAGS，LDFLAGS）
	Written     map[string]bool
	Name        map[string]*Name // 文件的累积名称
	ExpFunc     []*ExpFunc       // 文件的累积EXPFNC 
	Decl        []ast.Decl
	GoFiles     []string        // Go文件列表
	GccFiles    []string        // gcc输出文件列表
	Preamble    string          // 为(U cgo)导出收集的序言。h 
	typedefs    map[string]bool // 出现在我们感兴趣的对象类型中的类型名
	typedefList []typedefInfo
}

// typedefInfo是包中的一个元素。typedefList:typedef名称
// 以及需要它的位置。
type typedefInfo struct {
	typedef string
	pos     token.Pos
}

// 一个文件收集关于单个Go输入文件的信息。
type File struct {
	AST      *ast.File           // 解析的AST 
	Comments []*ast.CommentGroup // 文件中的注释
	Package  string              // 包名
	Preamble string              // C序言（导入“C”时的文档注释）
	Ref      []*Ref              // AST 
	Name     map[string]*Name    // 从Go name映射到name 
	NamePos  map[*Name]token.Pos // 映射自nameto position of the first reference 
	Edit     *edit.Buffer
}

func (f *File) offset(p token.Pos) int {
	return fset.Position(p).Offset
}

func nameKeys(m map[string]*Name) []string {
	var ks []string
	for k := range m {
		ks = append(ks, k)
	}
	sort.Strings(ks)
	return ks
}

// 调用是指在AST中调用C.xxx函数。
type Call struct {
	Call     *ast.CallExpr
	Deferred bool
	Done     bool
}

// A Ref指的是AST中形式为C.xxx的表达式。
type Ref struct {
	Name    *Name
	Expr    *ast.Expr
	Context astContext
	Done    bool
}

func (r *Ref) Pos() token.Pos {
	return (*r.Expr).Pos()
}

var nameKinds = []string{"iconst", "fconst", "sconst", "type", "var", "fpvar", "func", "macro", "not-type"}

// 一个名字收集关于C.xxx的信息。
type Name struct {
	Go       string // Go中使用的名称指的是C包
	Mangle   string // 
	FuncType *FuncType
	AddError bool
}

func (n *Name) IsVar() bool {
	return n.Kind == "var" || n.Kind == "fpvar"
}

func (n *Name) IsConst() bool {
	return strings.HasSuffix(n.Kind, "const")
}

// ExpFunc是一个导出函数，可从C调用。
// 此类函数在Go输入文件
// 中由包含行
type ExpFunc struct {
	Func    *ast.FuncDecl
	ExpName string // 要从C 
	Doc     string
}

// 使用的名称的文档注释标识。TypeRepr包含类型的字符串表示。
type TypeRepr struct {
	Repr       string
	FormatArgs []interface{}
}

// 类型在C和Go世界中收集关于类型的信息。
type Type struct {
	Size       int64
	Align      int64
	C          *TypeRepr
	Go         ast.Expr
	EnumValues map[string]int64
	Typedef    string
	BadPointer bool // 此指针类型应表示为uintptr（已弃用）
	NotInHeap  bool // 此类型应具有go:notinheap注释
}

// FuncType在C和go世界中收集有关函数类型的信息。
type FuncType struct {
	Params []*Type
	Result *Type
	Go     *ast.FuncType
}

func usage() {
	fmt.Fprint(os.Stderr, "usage: cgo -- [compiler options] file.go ...\n")
	flag.PrintDefaults()
	os.Exit(2)
}

var ptrSizeMap = map[string]int64{
	"386":      4,
	"alpha":    8,
	"amd64":    8,
	"arm":      4,
	"arm64":    8,
	"m68k":     4,
	"mips":     4,
	"mipsle":   4,
	"mips64":   8,
	"mips64le": 8,
	"nios2":    4,
	"ppc":      4,
	"ppc64":    8,
	"ppc64le":  8,
	"riscv":    4,
	"riscv64":  8,
	"s390":     4,
	"s390x":    8,
	"sh":       4,
	"shbe":     4,
	"sparc":    4,
	"sparc64":  8,
}

var intSizeMap = map[string]int64{
	"386":      4,
	"alpha":    8,
	"amd64":    8,
	"arm":      4,
	"arm64":    8,
	"m68k":     4,
	"mips":     4,
	"mipsle":   4,
	"mips64":   8,
	"mips64le": 8,
	"nios2":    4,
	"ppc":      4,
	"ppc64":    8,
	"ppc64le":  8,
	"riscv":    4,
	"riscv64":  8,
	"s390":     4,
	"s390x":    8,
	"sh":       4,
	"shbe":     4,
	"sparc":    4,
	"sparc64":  8,
}

var cPrefix string

var fset = token.NewFileSet()

var dynobj = flag.String("dynimport", "", "if non-empty, print dynamic import data for that file")
var dynout = flag.String("dynout", "", "write -dynimport output to this file")
var dynpackage = flag.String("dynpackage", "main", "set Go package for -dynimport output")
var dynlinker = flag.Bool("dynlinker", false, "record dynamic linker information in -dynimport mode")

// 此标志用于引导新的Go实现，
// 生成与数据布局匹配的Go类型，以及
// 主机的C库和系统调用中使用的常量值。
var godefs = flag.Bool("godefs", false, "for bootstrap: write Go definitions for C file to standard output")

var srcDir = flag.String("srcdir", "", "source directory")
var objDir = flag.String("objdir", "", "object directory")
var importPath = flag.String("importpath", "", "import path of package being built (for comments in generated files)")
var exportHeader = flag.String("exportheader", "", "where to write export header if any exported functions")

var gccgo = flag.Bool("gccgo", false, "generate files for use with gccgo")
var gccgoprefix = flag.String("gccgoprefix", "", "-fgo-prefix option used with gccgo")
var gccgopkgpath = flag.String("gccgopkgpath", "", "-fgo-pkgpath option used with gccgo")
var gccgoMangler func(string) string
var importRuntimeCgo = flag.Bool("import_runtime_cgo", true, "import runtime/cgo in generated code")
var importSyscall = flag.Bool("import_syscall", true, "import syscall in generated code")
var trimpath = flag.String("trimpath", "", "applies supplied rewrites or trims prefixes to recorded source file paths")

var goarch, goos, gomips, gomips64 string
var gccBaseCmd []string

func main() {
	objabi.AddVersionFlag() // -V 
	flag.Usage = usage
	flag.Parse()

	if *dynobj != "" {
		// /cgo-dynimport本质上是一个独立的助手命令
		// /内置于cgo二进制文件中。它扫描gcc生成的可执行文件
		// 并转储有关导入符号和
		// 导入库的信息。cgo的“go build”规则准备了一个
		// 适当的可执行文件，然后使用其导入信息
		// 而不需要让链接器复制所有
		// gcc关于在哪里查找导入的
		// 符号以及使用哪些符号的专业知识。
		dynimport(*dynobj)
		return
	}

	if *godefs {
		// 生成从头文件提取的定义，
		// 将被检入Go存储库。
		// 行号只是噪音。
		conf.Mode &^= printer.SourcePos
	}

	args := flag.Args()
	if len(args) < 1 {
		usage()
	}

	// 找到第一个看起来像go文件的arg，并假设在
	// 之前的所有内容都是要传递给gcc的选项。
	var i int
	for i = len(args); i > 0; i-- {
		if !strings.HasSuffix(args[i-1], ".go") {
			break
		}
	}
	if i == len(args) {
		usage()
	}

	goFiles := args[i:]

	for _, arg := range args[:i] {
		if arg == "-fsanitize=thread" {
			tsanProlog = yesTsanProlog
		}
		if arg == "-fsanitize=memory" {
			msanProlog = yesMsanProlog
		}
	}

	p := newPackage(args[:i])

	// 我们需要一个C编译器。看看这个。
	var err error
	gccBaseCmd, err = checkGCCBaseCmd()
	if err != nil {
		fatalf("%v", err)
		os.Exit(2)
	}

	// 记录外部链接环境中的CGO_LDFLAGS。
	if ldflags := os.Getenv("CGO_LDFLAGS"); ldflags != "" {
		args, err := splitQuoted(ldflags)
		if err != nil {
			fatalf("bad CGO_LDFLAGS: %q (%s)", ldflags, err)
		}
		p.addToFlag("LDFLAGS", args)
	}

	// 需要一个唯一的前缀来表示全局C符号，
	// 我们用来协调gcc和我们自己。
	// 我们已经把_cgo_u放在了开头，所以主要的
	// 关注的是相同函数的其他cgo包装。
	// 使用输入的md5开头来消除歧义。
	h := md5.New()
	io.WriteString(h, *importPath)
	fs := make([]*File, len(goFiles))
	for i, input := range goFiles {
		if *srcDir != "" {
			input = filepath.Join(*srcDir, input)
		}

		// 为文件创建绝对路径，以便在错误
		// 消息中使用，并记录在调试行号信息中。
		// 这与工具链的其余部分匹配。见戈朗。org/issue/5122。hu jian jian cdefg
		if aname, err := filepath.Abs(input); err == nil {
			input = aname
		}

		b, err := ioutil.ReadFile(input)
		if err != nil {
			fatalf("%s", err)
		}
		if _, err = h.Write(b); err != nil {
			fatalf("%s", err)
		}

		input, _ = objabi.ApplyRewrites(input, *trimpath)
		goFiles[i] = input

		f := new(File)
		f.Edit = edit.NewBuffer(b)
		f.ParseGo(input, b)
		f.DiscardCgoDirectives()
		fs[i] = f
	}

	cPrefix = fmt.Sprintf("_%x", h.Sum(nil)[0:6])

	if *objDir == "" {
		// 确保_obj目录存在，这样我们就可以在那里写入
		// 所有的输出文件。
		os.Mkdir("_obj", 0777)
		*objDir = "_obj"
	}
	*objDir += string(filepath.Separator)

	for i, input := range goFiles {
		f := fs[i]
		p.Translate(f)
		for _, cref := range f.Ref {
			switch cref.Context {
			case ctxCall, ctxCall2:
				if cref.Name.Kind != "type" {
					break
				}
				old := *cref.Expr
				*cref.Expr = cref.Name.Type.Go
				f.Edit.Replace(f.offset(old.Pos()), f.offset(old.End()), gofmt(cref.Name.Type.Go))
			}
		}
		if nerrors > 0 {
			os.Exit(2)
		}
		p.PackagePath = f.Package
		p.Record(f)
		if *godefs {
			os.Stdout.WriteString(p.godefs(f))
		} else {
			p.writeOutput(f, input)
		}
	}

	if !*godefs {
		p.writeDefs()
	}
	if nerrors > 0 {
		os.Exit(2)
	}
}

func newPackage(args []string) *Package {
	goarch = runtime.GOARCH
	if s := os.Getenv("GOARCH"); s != "" {
		goarch = s
	}
	goos = runtime.GOOS
	if s := os.Getenv("GOOS"); s != "" {
		goos = s
	}
	buildcfg.Check()
	gomips = buildcfg.GOMIPS
	gomips64 = buildcfg.GOMIPS64
	ptrSize := ptrSizeMap[goarch]
	if ptrSize == 0 {
		fatalf("unknown ptrSize for $GOARCH %q", goarch)
	}
	intSize := intSizeMap[goarch]
	if intSize == 0 {
		fatalf("unknown intSize for $GOARCH %q", goarch)
	}

	// 重置语言环境变量，以便gcc发出英语错误[sic]。
	os.Setenv("LANG", "en_US.UTF-8")
	os.Setenv("LC_ALL", "C")

	p := &Package{
		PtrSize:  ptrSize,
		IntSize:  intSize,
		CgoFlags: make(map[string][]string),
		Written:  make(map[string]bool),
	}
	p.addToFlag("CFLAGS", args)
	return p
}

// 记录关于f需要记录的内容。
func (p *Package) Record(f *File) {
	if p.PackageName == "" {
		p.PackageName = f.Package
	} else if p.PackageName != f.Package {
		error_(token.NoPos, "inconsistent package names: %s, %s", p.PackageName, f.Package)
	}

	if p.Name == nil {
		p.Name = f.Name
	} else {
		for k, v := range f.Name {
			if p.Name[k] == nil {
				p.Name[k] = v
			} else if p.incompleteTypedef(p.Name[k].Type) {
				p.Name[k] = v
			} else if p.incompleteTypedef(v.Type) {
				// 无事可做。
			} else if _, ok := nameToC[k]; ok {
				// 如果一些文件定义了名称，而另一些文件没有定义名称，那么我们预定义的名称可能会出现不一致的情况。
				// 问题26743。
			} else if !reflect.DeepEqual(p.Name[k], v) {
				error_(token.NoPos, "inconsistent definitions for C.%s", fixGo(k))
			}
		}
	}

	if f.ExpFunc != nil {
		p.ExpFunc = append(p.ExpFunc, f.ExpFunc...)
		p.Preamble += "\n" + f.Preamble
	}
	p.Decl = append(p.Decl, f.AST.Decls...)
}

// 不完整的类型定义报告t是否为不完整的
// 类型定义。
func (p *Package) incompleteTypedef(t *Type) bool {
	return t == nil || (t.Size == 0 && t.Align == -1)
}
